git - commit convention

Posted: 2025-11-12 Tags: git

contents

Git 커밋 컨벤션은 커밋 메시지 형식을 정하는 일련의 규칙입니다. 그 목적은 사람과 자동화 도구 모두에게 유용한, 깨끗하고 표준화되었으며 쉽게 파싱할 수 있는 커밋 히스토리(로그)를 만드는 것입니다.

가장 인기 있고 널리 채택된 표준은 Conventional Commits(관례적인 커밋) 라고 불립니다. 이는 모든 커밋에 대해 간단하고 구조화된 형식을 제공합니다.

커밋 컨벤션을 사용하는 이유

"버그 수정" 또는 "추가 작업"처럼 무작위적인 메시지로 코드를 커밋하면 프로젝트 히스토리를 쓸모없게 만듭니다. 컨벤션을 채택하면 네 가지 주요 이점이 있습니다.

🤖 자동 CHANGELOG 생성: 도구가 커밋 히스토리를 파싱하여 릴리즈 노트를 위한 CHANGELOG.md 파일을 자동으로 생성할 수 있습니다.
🤖 자동 버전 관리: 커밋 타입(feat, fix, BREAKING CHANGE)을 사용하여 시맨틱 버저닝(SemVer) 에 따라 다음 버전 번호를 자동으로 결정할 수 있습니다.
- feat는 마이너(minor) 버전을 올립니다 (예: 1.2.0 -> 1.3.0).
- fix는 패치(patch) 버전을 올립니다 (예: 1.2.0 -> 1.2.1).
- BREAKING CHANGE:가 포함된 커밋은 메이저(major) 버전을 올립니다 (예: 1.2.0 -> 2.0.0).
📖 가독성 향상: git log가 프로젝트의 진화 과정을 보여주는 명확하고 스캔하기 쉬운 기록이 됩니다. 누구나 무엇이 왜 변경되었는지 빠르게 이해할 수 있습니다.
🎯 쉬운 디버깅: 버그를 찾을 때 docs나 style 같은 커밋은 쉽게 건너뛸 수 있습니다. git bisect와 같은 도구가 훨씬 더 효과적이 됩니다.

Conventional Commit의 구조

Conventional Commit 메시지는 세 가지 주요 부분으로 구성됩니다.

<타입>[선택적 스코프]: <제목>
<빈 줄>
[선택적 본문]
<빈 줄>
[선택적 꼬리말]

1. 헤더 (필수)

헤더는 가장 중요한 세 가지 정보를 포함하는 한 줄입니다.

<타입> 수행한 변경의 종류를 설명합니다. 짧은 소문자 키워드입니다. 가장 일반적인 유형은 다음 섹션에 나열되어 있습니다.

[선택적 스코프] 이 커밋이 영향을 미치는 코드베이스의 부분을 지정하는 명사입니다 (괄호 안에).

feat(api): ...
fix(auth): ...
docs(readme): ...

<제목> 변경 사항에 대한 짧고 설명적인 요약입니다.

명령형으로 작성: "added feature" (나쁨) 대신 "add feature" (좋음). "이 커밋을 적용하면... 기능을 추가할 것이다."라는 문장을 완성한다고 생각하세요.
소문자로 시작합니다.
마침표로 끝내지 않습니다.
약 50자 이내로 제한하여 잘리지 않도록 합니다.

2. 본문 (선택 사항)

본문은 변경 사항에 대한 더 자세한 맥락을 제공하는 데 사용됩니다.

헤더와 반드시 한 줄의 빈 줄로 구분되어야 합니다.
"어떻게"가 아닌 변경의 "왜"와 "무엇을" 설명합니다.
터미널에서의 가독성을 위해 일반적으로 72자에서 줄 바꿈하는 것이 좋습니다.

3. 꼬리말 (선택 사항)

꼬리말은 메타데이터에 사용되며 본문과 반드시 한 줄의 빈 줄로 구분되어야 합니다.

BREAKING CHANGES (주요 변경 사항): 꼬리말의 가장 중요한 부분입니다. 하위 호환성이 없는 변경을 도입하는 커밋은 반드시 꼬리말을 BREAKING CHANGE:로 시작해야 합니다. 이는 메이저 버전 변경(SemVer의 MAJOR)을 신호합니다.
이슈 트래킹: 이슈를 참조하고 종료하는 데에도 사용됩니다.
- Fixes: #123
- Closes: #456, #789

일반적인 커밋 타입 (어휘)

다음은 Conventional Commits 명세에 정의된 가장 일반적인 타입입니다.

feat: 사용자를 위한 새로운 기능 (예: feat: add user login page).
fix: 사용자를 위한 버그 수정 (예: fix: correct password reset logic).
docs: 문서 변경 사항만 (예: docs: update README with setup guide).
style: 코드의 의미에 영향을 주지 않는 변경 사항 (공백, 서식, 세미콜론 누락 등).
refactor: 버그를 수정하거나 기능을 추가하지 않는 코드 변경. 변수 이름 변경이나 함수 분리와 같은 구조적 개선을 위한 것입니다.
test: 누락된 테스트 추가 또는 기존 테스트 수정.
chore: 운영 코드를 수정하지 않는 빌드 프로세스, 툴링 또는 보조 작업 변경 (예: chore: update npm dependencies).
perf: 성능을 향상시키는 코드 변경.

전체 예시

모든 부분을 사용한 복잡한 커밋 메시지의 예는 다음과 같습니다.

feat(auth): add OAuth 2.0 login flow

새로운 인증 제공자로 Google의 OIDC 호환 전체 흐름을 구현합니다.
이를 통해 사용자는 원클릭으로 가입하고 로그인할 수 있습니다.

이 변경은 사용 중단될 예정인 기존의 username/password 시스템을
대체하기 위해 필요합니다.

BREAKING CHANGE: /login API 엔드포인트는 더 이상 username과
password를 받지 않습니다. 이제 제공자로부터 받은 `id_token`을
포함한 `POST` 요청을 기대합니다.

Fixes: #123, #456

컨벤션을 강제하는 방법 (도구)

이러한 규칙을 일일이 기억할 필요는 없습니다. 팀은 도구를 사용하여 자동으로 강제합니다.

Commitizen: 타입, 스코프, 제목 등을 대화형으로 묻고 커밋 메시지를 대신 만들어주는 커맨드 라인 도구입니다.
Commitlint: 커밋이 생성되기 전 에 커밋 메시지가 규칙을 준수하는지 확인하는 린터(linter)입니다.
Husky: Git 훅(예: commit-msg 훅)을 사용하여 commitlint와 같은 스크립트를 쉽게 실행할 수 있게 해주는 도구입니다.

references